Document GtkTreeIterCompareFunc (#154943)

2004-10-11  Matthias Clasen  <mclasen@redhat.com>

	* gtk/tmpl/gtktreesortable.sgml: Document GtkTreeIterCompareFunc
	(#154943)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 0b88c26796be56518c365bb4041f76984d5cf411..a5a053cfeeee9e2a7689f1ddce7031f1385d7c3a 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2004-10-11  Matthias Clasen  <mclasen@redhat.com>
+
+       * gtk/tmpl/gtktreesortable.sgml: Document GtkTreeIterCompareFunc
+       (#154943)
+
 2004-10-10  Matthias Clasen  <matthias@localhost.localdomain>
 
        * gtk/images/progressbar.png:

diff --git a/docs/reference/gtk/tmpl/gtktreesortable.sgml b/docs/reference/gtk/tmpl/gtktreesortable.sgml
index f58e9e6ab1e729a3dc6d91e55b45b4ecf2ecc735..ee721423b5d06d8fe2840bef526b289ae6bad7dd 100644 (file)
--- a/docs/reference/gtk/tmpl/gtktreesortable.sgml
+++ b/docs/reference/gtk/tmpl/gtktreesortable.sgml
@@ -42,15 +42,24 @@ The interface for sortable models used by GtkTreeView
 
 <!-- ##### USER_FUNCTION GtkTreeIterCompareFunc ##### -->
 <para>
-
+A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive
+integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b
+respectively. If two iters compare as equal, their order in the sorted model 
+is undefined. In order to ensure that the #GtkTreeSortable behaves as 
+expected, the GtkTreeIterCompareFunc must define a partial order on 
+the model, i.e. it must be reflexive, antisymmetric and transitive.
+</para>
+<para>
+For example, if @model is a product catalogue, then a compare function
+for the "price" column could be one which returns 
+<literal>price_of(@a) - price_of(@b)</literal>.
 </para>
 
-@model: 
-@a: 
-@b: 
-@user_data: 
-@Returns: 
-
+@model: The #GtkTreeModel the comparison is within
+@a: A #GtkTreeIter in @model
+@b: Another #GtkTreeIter in @model
+@user_data: Data passed when the compare func is assigned e.g. by
+gtk_tree_sortable_set_sort_func()
 
 <!-- ##### FUNCTION gtk_tree_sortable_sort_column_changed ##### -->
 <para>